Skip to content

fix: affinity selection scored a protein the cell does not express - #51

Merged
MuteJester merged 3 commits into
masterfrom
engine/affinity-translation
Nov 5, 2026
Merged

MuteJester merged 3 commits into
masterfrom
engine/affinity-translation

Conversation

@MuteJester

Copy link
Copy Markdown
Owner

Affinity selection translated each region of a cell separately and
concatenated the results. compute_codon_rail keeps a codon only if it fits
wholly inside one region, so every codon straddling a region boundary was
dropped — and every region boundary in a rearrangement is a junction boundary.

What it cost

A cell grown with rate=0, and therefore identical to its founder, scored
against the founder's own protein reported an affinity of 3.57e-67 instead of
1.0.
The model could not recognise a cell as identical to itself.

Measured over 200 human_igh records:

Codons dropped per record 2.68 mean, range 0–4
Dropped codons touching the junction 536 of 536
By boundary V+NP1 153, D+NP2 126, NP1+D 119, NP2+J 119, three-region 19

The frame did not restart — each region's phase is its pool offset, so every
scored codon was real. The dropped ones simply vanished and shifted every
amino-acid position after them left. For one record the scored protein began
VYYCARGYCSSTSC where the real one is VYYCARDRGYCSSTSC*KK: the loss starts
at the conserved CDR3 anchor and carries through CDR3 and J. Records whose
boundaries happen to be codon-aligned lose nothing, which is why the count is
not simply one per boundary.

A stop codon scored as the perfect antibody

Separately, substitution_cost is S(a,a) - S(a,b), and for a stop or an
unresolved X both terms fell through to the same -4. The cost cancelled to
exactly zero against every target residue, so distance was 0 and
affinity = exp(-beta · 0) = 1.0, the maximum. A KPGT* cell reported affinity
1.0 against KPGTA, KPGTW and KPGTAAAAAAAA alike. The asymmetry is the
tell: a stop in the target cost the full amount, a stop in the cell was free.

Two comments were also wrong — blosum62 claimed non-standard residues
"contribute maximally to distance", which the cancellation made false, and
substitution_cost claimed its result grows as the substitution becomes less
favourable, true for every pair except the ones that matter most.

The fix

Both paths now use the continuous coding-span translation the duplex and
family-replay paths already used, renamed duplex_sim_to_aa →
coding_sim_to_aa because it was never duplex-specific. It agrees with the
record's own sequence_aa, which the projection derives independently from
coding_frame_start — and that independence is what makes the new tests
evidence rather than a tautology.

The reference is not optional: coding_span resolves the frame from the V
allele's native phase, its 5' trim and its observation loss, so translating from
pool position zero can be in the wrong frame entirely. An affinity model
therefore travels paired with its RefDataConfig rather than borrowing one
from the mutation context — passing a context also selects the mutator's
execution policy, so giving the neutral path one just to reach its reference
would move its draws. simulate_lineage now requires refdata when selection
is active.

A non-residue is charged the maximal substitution cost (15, S(W,W) - S(W,D),
derived from the matrix by its own test rather than trusted).

A supplied target_aa must now be exactly as long as the receptor it scores.
The distance compared min(len, len) positions and ignored the rest, so a
truncated or over-long target scored silently and reported a number that was not
a distance to it.

A stop is penalised, not lethal — and why

Lethality was the intended rule and had to be withdrawn after measuring what it
costs. Share of sampled human_igh cells whose coding span contains a stop:

SHM rate cells with a stop
0.05 (the default) 96% (110/115)
0.01 89% (102/114)
0.0 50% — inherited from founders

and 108 of 200 default founders (54%) carry one already, because recombine()
does not constrain productivity and clonal_lineage does not require it.
Giving those cells no offspring extinguishes essentially every family and makes
clonal_lineage(selection_strength>0) fail outright after its 50 survival
retries. That the mutation model produces mostly untranslatable receptors is a
separate problem from how affinity scores them; making lethality viable means
constraining SHM to keep the receptor productive first. The 96% figure is in the
guide and changelog so lineage_affinity on a stop-bearing cell is not read as
a statement that the cell is viable.

Tests

tests/components/clonal/test_lineage_affinity_translation.py pins the
translation against the independent sequence_aa oracle, verified to equal a
continuous translation of the coding span before being relied on.

Two existing tests encoded the defect's assumptions.
test_affinity_selection_raises_mean_affinity used target_aa="A" * 100 with
the note "target length need not match; distance uses min length" — the defect
stated as a design choice. test_clonal_lineage_selection_raises_mean_affinity
is replaced rather than repaired
: its 100-residue target made every affinity
underflow to near zero, which is what made its comparison stable, and with real
distances the claim is not stably testable at DSL level (over 7–17 sampled cells
the mean is sampling noise — 0.637, 0.642, 0.634, 0.631, 0.628, 0.651 across
strengths 0.05–0.7). The claim stays at engine level where the founder can be
pinned and the target sized; the successor keeps what only the DSL can break.
The inventory declaration carries the full argument.

The three affinity growth tests scored the broken rail on a four-base synthetic
founder with no V assignment. They now use a founder with a resolved assignment
and its reference. That fixture's pool is AAA TGT ACT TTT AAA — every boundary
codon-aligned — which is exactly why they passed before.

Compatibility

DETERMINISM_VERSION 3 → 4. Seed-moving wherever selection is active;
selection_strength=0 runs with no target are unaffected. The six
reproducibility goldens differ in one field, determinism_version — no golden
grows a lineage or scores an affinity, so nothing there measures the new model.

Affinity numbers from before version 4 are not comparable with these, and
neither are the genealogies selection shaped. Neither "all published results
invalid" nor "few runs affected" is established
— that needs an audit of
released runs with selection_strength > 0.

Not claimed

This validates the input to the selection model. BLOSUM62 distance to an
artificial receptor-sequence target remains a synthetic fitness landscape, not
antigen binding, and the per-position weights are still uniform despite a
comment promising CDR3 weighting.

Gates

pytest 5865 passed / 17 skipped; performance 9 passed serial; cargo 1742 passed
across 6 suites; ruff clean; inventory gate clean with --declarations.

`blosum62` falls through to -4 for any character outside the twenty
residues, and `substitution_cost` is `S(a,a) - S(a,b)`. For a stop or an
unresolved `X` in the cell both terms were that same -4, so the cost
cancelled to exactly zero against every target residue, distance was 0,
and `affinity = exp(-beta * 0) = 1.0` -- the maximum. A cell whose
receptor cannot be translated scored as a perfect match to any antigen.

The asymmetry is what gives it away: a stop in the *target* cost the
full amount, a stop in the cell was free. Reproduced on the real model:
a `KPGT*` cell reported affinity 1.0 against `KPGTA`, `KPGTW` and
`KPGTAAAAAAAA` alike.

A character that is not a residue is now charged
`MAX_SUBSTITUTION_COST`, so it cannot be cheaper than a substitution
between two real residues. The constant is 15 -- `S(W,W) - S(W,D)` --
and `max_real_substitution_cost_is_the_constant` derives that maximum
from the matrix rather than trusting the number.

Two comments were also wrong. `blosum62` claimed non-standard residues
"contribute maximally to distance", which the cancellation made false,
and `substitution_cost` claimed its result "grows as the substitution
becomes less favorable", which held for every pair except the ones that
matter most. The maximal-contribution rule now lives where it can see
which side the non-residue is on, and `idx` is lifted out of `blosum62`
as `residue_index` so both can use it.

This is the smaller half of the defect. The translation that decides
which residues are scored at all is still wrong; that is the next
commit, and it is what moves the determinism version.
`sim_to_aa` concatenated the per-region codon rail, and
`compute_codon_rail` keeps a codon only if it fits wholly inside one
region. Every region boundary in a rearrangement is a junction boundary,
so the residues selection could not see were exactly the ones it exists
to select on. Measured over 200 human_igh records: 2.68 codons dropped
per record, range 0 to 4, and 536 of 536 of them straddling V/NP1,
NP1/D, D/NP2 or NP2/J. The frame did not restart -- each region's phase
is its pool offset -- so every scored codon was real; the dropped ones
simply vanished and shifted the indices after them left.

For one record the scored protein began VYYCARGYCSSTSC where the real
one is VYYCARDRGYCSSTSC*KK: the loss starts at the conserved CDR3 anchor
and carries through CDR3 and J.

The end-to-end consequence, through the public API: a cell grown with
rate=0, so identical to its founder, scored against the founder's own
protein reported an affinity of 3.57e-67 instead of 1. The model could
not recognise a cell as identical to itself.

Both paths now use the continuous coding-span translation that the
duplex and family-replay paths already used, renamed from
`duplex_sim_to_aa` to `coding_sim_to_aa` because it was never
duplex-specific. It agrees with the record's own `sequence_aa`, which
the projection derives independently from `coding_frame_start`, and that
independence is what makes the new tests evidence rather than a
tautology.

The reference is not optional for this: `coding_span` resolves the frame
from the V allele's native phase, its 5' trim and its observation loss,
so translating from pool position zero can be in the wrong frame
entirely. An affinity model therefore travels with its `RefDataConfig`
as a pair rather than borrowing one from the mutation context -- passing
a context exists to select the mutator's execution policy, and giving the
neutral path one just to reach its reference would move its draws.
`simulate_lineage` now requires refdata when selection is active.

Under active selection a cell whose coding span contains a stop
expresses no receptor, receives no survival signal, and leaves no
offspring. Scoped to active selection deliberately: at
selection_strength 0 fitness is identically 1 for every cell, which is
documented and tested, and lethality is part of a selection model rather
than something to assert over a run the caller asked to be neutral.

A supplied target_aa must now be exactly as long as the receptor it is
scored against. `weighted_aa_distance` compares min(len, len) positions
and ignores the rest, so a truncated or over-long target scored silently
-- KPGTA and KPGTAAAAAAAA were equidistant from a cell. Validated at the
PyO3 boundary, where callers are; internal constructions still build
whatever they need for range tests.

The three affinity growth tests scored the broken rail on a four-base
synthetic founder with no V assignment. They now use a founder with a
resolved assignment and its reference. That fixture's boundaries are all
codon-aligned, which is why they passed before: it is the case that
drops nothing.

DETERMINISM_VERSION 3 -> 4. Seed-moving wherever selection is active.
Lethality was the intended rule and it had to be withdrawn. Measured on
human_igh, the share of sampled cells whose coding span contains a stop:
96% at the default rate=0.05 (110/115), 89% at 0.01, and 50% even at
rate=0, inherited from founders -- 108 of 200 of which carry one
already, because recombine() does not constrain productivity and
clonal_lineage does not require it.

Giving those cells no offspring extinguishes essentially every family,
and clonal_lineage(selection_strength>0) then fails outright after
exhausting its 50 survival retries. That is not a germinal center; it is
a mutation model that produces mostly untranslatable receptors, which is
a separate problem from how affinity scores them. A stop still carries
the maximal substitution cost, so a receptor that cannot be translated
is scored far from the target rather than as a perfect match, which was
the reproduced defect. Making lethality viable means constraining SHM to
keep the receptor productive first -- rejecting stop-causing proposals is
a different process from letting lethal mutations reduce survival, and it
has to come before this scoring change, not with it.

An earlier draft of the rule also applied at selection_strength 0, which
silently overrode the documented guarantee that fitness is identically 1
there. It passed affinity_strength_zero_matches_neutral_topology only
because that fixture's founder carries no stop.

The guide and changelog carry the 96% figure, so a reader does not take
lineage_affinity on a stop-bearing cell for a statement that the cell is
viable. They also record that a supplied target must match the
receptor's protein length, that the length is discoverable only from the
refusal (sampled cells are mutated descendants and differ in length),
and that this makes an explicit target single-clone in practice, since
each clone has its own founder.

Two affinity tests encoded the defect's assumptions and are updated
here. test_affinity_selection_raises_mean_affinity used
target_aa="A" * 100 with the note "target length need not match;
distance uses min length" -- the defect stated as a design choice. It now
builds a target from the founder's own protein, taken from the record
projection rather than the affinity path, so the length is right by
construction.

test_clonal_lineage_selection_raises_mean_affinity is replaced rather
than repaired, and the inventory declaration carries the argument. Its
100-residue target made every affinity underflow to near zero, which is
what made its comparison stable. With real distances the claim is not
stably testable at DSL level: over 7 to 17 sampled cells the mean is
sampling noise -- 0.637, 0.642, 0.634, 0.631, 0.628, 0.651 across
strengths 0.05 to 0.7 -- and a strength large enough to separate the arms
drives fitness to zero for diverged cells and extinguishes the family.
The claim stays at engine level where the founder can be pinned and the
target sized. The successor keeps what only the DSL can break: the
keyword reaching the engine, affinities populated and in range, and a
neutral run reporting 0.0 because it builds no model at all.

The six reproducibility goldens change by one field again,
determinism_version 3 to 4. No golden grows a lineage or scores an
affinity, so nothing here measures the new model.
@MuteJester
MuteJester merged commit 2ef07c6 into master Nov 5, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant